.TH "Session handling" 3spotify "Wed Mar 28 2012" "libspotify" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Session handling \- 
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBsp_audioformat\fP"
.br
.ti -1c
.RI "struct \fBsp_audio_buffer_stats\fP"
.br
.ti -1c
.RI "struct \fBsp_subscribers\fP"
.br
.ti -1c
.RI "struct \fBsp_offline_sync_status\fP"
.br
.ti -1c
.RI "struct \fBsp_session_callbacks\fP"
.br
.ti -1c
.RI "struct \fBsp_session_config\fP"
.br
.in -1c
.SS "Defines"

.in +1c
.ti -1c
.RI "#define \fBSPOTIFY_API_VERSION\fP   11"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef enum \fBsp_connectionstate\fP \fBsp_connectionstate\fP"
.br
.ti -1c
.RI "typedef enum \fBsp_sampletype\fP \fBsp_sampletype\fP"
.br
.ti -1c
.RI "typedef struct \fBsp_audioformat\fP \fBsp_audioformat\fP"
.br
.ti -1c
.RI "typedef enum \fBsp_bitrate\fP \fBsp_bitrate\fP"
.br
.ti -1c
.RI "typedef enum \fBsp_playlist_type\fP \fBsp_playlist_type\fP"
.br
.ti -1c
.RI "typedef enum \fBsp_search_type\fP \fBsp_search_type\fP"
.br
.ti -1c
.RI "typedef enum 
.br
\fBsp_playlist_offline_status\fP \fBsp_playlist_offline_status\fP"
.br
.ti -1c
.RI "typedef enum \fBsp_availability\fP \fBsp_track_availability\fP"
.br
.ti -1c
.RI "typedef enum 
.br
\fBsp_track_offline_status\fP \fBsp_track_offline_status\fP"
.br
.ti -1c
.RI "typedef struct 
.br
\fBsp_audio_buffer_stats\fP \fBsp_audio_buffer_stats\fP"
.br
.ti -1c
.RI "typedef struct \fBsp_subscribers\fP \fBsp_subscribers\fP"
.br
.ti -1c
.RI "typedef enum \fBsp_connection_type\fP \fBsp_connection_type\fP"
.br
.ti -1c
.RI "typedef enum \fBsp_connection_rules\fP \fBsp_connection_rules\fP"
.br
.ti -1c
.RI "typedef enum \fBsp_artistbrowse_type\fP \fBsp_artistbrowse_type\fP"
.br
.ti -1c
.RI "typedef struct 
.br
\fBsp_offline_sync_status\fP \fBsp_offline_sync_status\fP"
.br
.ti -1c
.RI "typedef struct \fBsp_session_callbacks\fP \fBsp_session_callbacks\fP"
.br
.ti -1c
.RI "typedef struct \fBsp_session_config\fP \fBsp_session_config\fP"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBsp_connectionstate\fP { \fBSP_CONNECTION_STATE_LOGGED_OUT\fP =  0, \fBSP_CONNECTION_STATE_LOGGED_IN\fP =  1, \fBSP_CONNECTION_STATE_DISCONNECTED\fP =  2, \fBSP_CONNECTION_STATE_UNDEFINED\fP =  3, \fBSP_CONNECTION_STATE_OFFLINE\fP =  4 }"
.br
.ti -1c
.RI "enum \fBsp_sampletype\fP { \fBSP_SAMPLETYPE_INT16_NATIVE_ENDIAN\fP =  0 }"
.br
.ti -1c
.RI "enum \fBsp_bitrate\fP { \fBSP_BITRATE_160k\fP =  0, \fBSP_BITRATE_320k\fP =  1, \fBSP_BITRATE_96k\fP =  2 }"
.br
.ti -1c
.RI "enum \fBsp_playlist_type\fP { \fBSP_PLAYLIST_TYPE_PLAYLIST\fP =  0, \fBSP_PLAYLIST_TYPE_START_FOLDER\fP =  1, \fBSP_PLAYLIST_TYPE_END_FOLDER\fP =  2, \fBSP_PLAYLIST_TYPE_PLACEHOLDER\fP =  3 }"
.br
.ti -1c
.RI "enum \fBsp_search_type\fP "
.br
.ti -1c
.RI "enum \fBsp_playlist_offline_status\fP { \fBSP_PLAYLIST_OFFLINE_STATUS_NO\fP =  0, \fBSP_PLAYLIST_OFFLINE_STATUS_YES\fP =  1, \fBSP_PLAYLIST_OFFLINE_STATUS_DOWNLOADING\fP =  2, \fBSP_PLAYLIST_OFFLINE_STATUS_WAITING\fP =  3 }"
.br
.ti -1c
.RI "enum \fBsp_availability\fP { \fBSP_TRACK_AVAILABILITY_UNAVAILABLE\fP =  0, \fBSP_TRACK_AVAILABILITY_AVAILABLE\fP =  1, \fBSP_TRACK_AVAILABILITY_NOT_STREAMABLE\fP =  2, \fBSP_TRACK_AVAILABILITY_BANNED_BY_ARTIST\fP =  3 }"
.br
.ti -1c
.RI "enum \fBsp_track_offline_status\fP { \fBSP_TRACK_OFFLINE_NO\fP =  0, \fBSP_TRACK_OFFLINE_WAITING\fP =  1, \fBSP_TRACK_OFFLINE_DOWNLOADING\fP =  2, \fBSP_TRACK_OFFLINE_DONE\fP =  3, \fBSP_TRACK_OFFLINE_ERROR\fP =  4, \fBSP_TRACK_OFFLINE_DONE_EXPIRED\fP =  5, \fBSP_TRACK_OFFLINE_LIMIT_EXCEEDED\fP =  6, \fBSP_TRACK_OFFLINE_DONE_RESYNC\fP =  7 }"
.br
.ti -1c
.RI "enum \fBsp_connection_type\fP { \fBSP_CONNECTION_TYPE_UNKNOWN\fP =  0, \fBSP_CONNECTION_TYPE_NONE\fP =  1, \fBSP_CONNECTION_TYPE_MOBILE\fP =  2, \fBSP_CONNECTION_TYPE_MOBILE_ROAMING\fP =  3, \fBSP_CONNECTION_TYPE_WIFI\fP =  4, \fBSP_CONNECTION_TYPE_WIRED\fP =  5 }"
.br
.ti -1c
.RI "enum \fBsp_connection_rules\fP { \fBSP_CONNECTION_RULE_NETWORK\fP =  0x1, \fBSP_CONNECTION_RULE_NETWORK_IF_ROAMING\fP =  0x2, \fBSP_CONNECTION_RULE_ALLOW_SYNC_OVER_MOBILE\fP =  0x4, \fBSP_CONNECTION_RULE_ALLOW_SYNC_OVER_WIFI\fP =  0x8 }"
.br
.ti -1c
.RI "enum \fBsp_artistbrowse_type\fP { \fBSP_ARTISTBROWSE_FULL\fP, \fBSP_ARTISTBROWSE_NO_TRACKS\fP, \fBSP_ARTISTBROWSE_NO_ALBUMS\fP }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBsp_error\fP \fBsp_session_create\fP (const \fBsp_session_config\fP *config, \fBsp_session\fP **sess)"
.br
.ti -1c
.RI "void \fBsp_session_release\fP (\fBsp_session\fP *sess)"
.br
.ti -1c
.RI "void \fBsp_session_login\fP (\fBsp_session\fP *session, const char *username, const char *password, bool remember_me, const char *blob)"
.br
.ti -1c
.RI "\fBsp_error\fP \fBsp_session_relogin\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "int \fBsp_session_remembered_user\fP (\fBsp_session\fP *session, char *buffer, size_t buffer_size)"
.br
.ti -1c
.RI "void \fBsp_session_forget_me\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "\fBsp_user\fP * \fBsp_session_user\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "void \fBsp_session_logout\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "void \fBsp_session_flush_caches\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "\fBsp_connectionstate\fP \fBsp_session_connectionstate\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "void * \fBsp_session_userdata\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "void \fBsp_session_set_cache_size\fP (\fBsp_session\fP *session, size_t size)"
.br
.ti -1c
.RI "void \fBsp_session_process_events\fP (\fBsp_session\fP *session, int *next_timeout)"
.br
.ti -1c
.RI "\fBsp_error\fP \fBsp_session_player_load\fP (\fBsp_session\fP *session, \fBsp_track\fP *track)"
.br
.ti -1c
.RI "void \fBsp_session_player_seek\fP (\fBsp_session\fP *session, int offset)"
.br
.ti -1c
.RI "void \fBsp_session_player_play\fP (\fBsp_session\fP *session, bool play)"
.br
.ti -1c
.RI "void \fBsp_session_player_unload\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "\fBsp_error\fP \fBsp_session_player_prefetch\fP (\fBsp_session\fP *session, \fBsp_track\fP *track)"
.br
.ti -1c
.RI "\fBsp_playlistcontainer\fP * \fBsp_session_playlistcontainer\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "\fBsp_playlist\fP * \fBsp_session_inbox_create\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "\fBsp_playlist\fP * \fBsp_session_starred_create\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "\fBsp_playlist\fP * \fBsp_session_starred_for_user_create\fP (\fBsp_session\fP *session, const char *canonical_username)"
.br
.ti -1c
.RI "\fBsp_playlistcontainer\fP * \fBsp_session_publishedcontainer_for_user_create\fP (\fBsp_session\fP *session, const char *canonical_username)"
.br
.ti -1c
.RI "void \fBsp_session_preferred_bitrate\fP (\fBsp_session\fP *session, \fBsp_bitrate\fP bitrate)"
.br
.ti -1c
.RI "void \fBsp_session_preferred_offline_bitrate\fP (\fBsp_session\fP *session, \fBsp_bitrate\fP bitrate, bool allow_resync)"
.br
.ti -1c
.RI "bool \fBsp_session_get_volume_normalization\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "void \fBsp_session_set_volume_normalization\fP (\fBsp_session\fP *session, bool on)"
.br
.ti -1c
.RI "void \fBsp_session_set_connection_type\fP (\fBsp_session\fP *session, \fBsp_connection_type\fP type)"
.br
.ti -1c
.RI "void \fBsp_session_set_connection_rules\fP (\fBsp_session\fP *session, \fBsp_connection_rules\fP rules)"
.br
.ti -1c
.RI "int \fBsp_offline_tracks_to_sync\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "int \fBsp_offline_num_playlists\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "bool \fBsp_offline_sync_get_status\fP (\fBsp_session\fP *session, \fBsp_offline_sync_status\fP *status)"
.br
.ti -1c
.RI "int \fBsp_offline_time_left\fP (\fBsp_session\fP *session)"
.br
.ti -1c
.RI "int \fBsp_session_user_country\fP (\fBsp_session\fP *session)"
.br
.in -1c
.SH "Detailed Description"
.PP 
The concept of a session is fundamental for all communication with the Spotify ecosystem - it is the object responsible for communicating with the Spotify service\&. You will need to instantiate a session that then can be used to request artist information, perform searches etc\&. 
.SH "Define Documentation"
.PP 
.SS "#define \fBSPOTIFY_API_VERSION\fP   11"
Current version of the application interface, that is, the API described by this file\&.
.PP
This value should be set in the \fBsp_session_config\fP struct passed to \fBsp_session_create()\fP\&.
.PP
If an (upgraded) library is no longer compatible with this version the error \fBSP_ERROR_BAD_API_VERSION\fP will be returned from \fBsp_session_create()\fP\&. Future versions of the library will provide you with some kind of mechanism to request an updated version of the library\&. 
.PP
\fBExamples: \fP
.in +1c
\fBjukebox\&.c\fP\&.
.SH "Typedef Documentation"
.PP 
.SS "typedef enum \fBsp_artistbrowse_type\fP  \fBsp_artistbrowse_type\fP"
Controls the type of data that will be included in artist browse queries 
.SS "typedef struct \fBsp_audio_buffer_stats\fP  \fBsp_audio_buffer_stats\fP"
Buffer stats used by get_audio_buffer_stats callback 
.SS "typedef struct \fBsp_audioformat\fP  \fBsp_audioformat\fP"
Audio format descriptor 
.SS "typedef enum \fBsp_bitrate\fP  \fBsp_bitrate\fP"
Bitrate definitions for music streaming 
.SS "typedef enum \fBsp_connection_rules\fP  \fBsp_connection_rules\fP"
Connection rules, bitwise OR of flags
.PP
The default is SP_CONNECTION_RULE_NETWORK | SP_CONNECTION_RULE_ALLOW_SYNC 
.SS "typedef enum \fBsp_connection_type\fP  \fBsp_connection_type\fP"
Current connection type set using \fBsp_session_set_connection_type()\fP 
.SS "typedef enum \fBsp_connectionstate\fP  \fBsp_connectionstate\fP"
Describes the current state of the connection 
.SS "typedef struct \fBsp_offline_sync_status\fP  \fBsp_offline_sync_status\fP"
Offline sync status 
.SS "typedef enum \fBsp_playlist_offline_status\fP  \fBsp_playlist_offline_status\fP"
Playlist offline status 
.SS "typedef enum \fBsp_playlist_type\fP  \fBsp_playlist_type\fP"
Playlist types 
.SS "typedef enum \fBsp_sampletype\fP  \fBsp_sampletype\fP"
Sample type descriptor 
.SS "typedef enum \fBsp_search_type\fP  \fBsp_search_type\fP"
Search types 
.SS "typedef struct \fBsp_session_callbacks\fP  \fBsp_session_callbacks\fP"
Session callbacks
.PP
Registered when you create a session\&. If some callbacks should not be of interest, set them to NULL\&. 
.SS "typedef struct \fBsp_session_config\fP  \fBsp_session_config\fP"
Session config 
.SS "typedef struct \fBsp_subscribers\fP  \fBsp_subscribers\fP"
List of subscribers returned by \fBsp_playlist_subscribers()\fP 
.SS "typedef enum \fBsp_availability\fP  \fBsp_track_availability\fP"
Track availability 
.SS "typedef enum \fBsp_track_offline_status\fP  \fBsp_track_offline_status\fP"
Track offline status 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBsp_artistbrowse_type\fP"
Controls the type of data that will be included in artist browse queries 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_ARTISTBROWSE_FULL \fP\fP
All information except tophit tracks This mode is deprecated and will removed in a future release 
.TP
\fB\fISP_ARTISTBROWSE_NO_TRACKS \fP\fP
Only albums and data about them, no tracks\&. In other words, \fBsp_artistbrowse_num_tracks()\fP will return 0 
.TP
\fB\fISP_ARTISTBROWSE_NO_ALBUMS \fP\fP
Only return data about the artist (artist name, similar artist biography, etc No tracks or album will be abailable\&. \fBsp_artistbrowse_num_tracks()\fP and \fBsp_artistbrowse_num_albums()\fP will both return 0 
.SS "enum \fBsp_availability\fP"
Track availability 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_TRACK_AVAILABILITY_UNAVAILABLE \fP\fP
Track is not available\&. 
.TP
\fB\fISP_TRACK_AVAILABILITY_AVAILABLE \fP\fP
Track is available and can be played\&. 
.TP
\fB\fISP_TRACK_AVAILABILITY_NOT_STREAMABLE \fP\fP
Track can not be streamed using this account\&. 
.TP
\fB\fISP_TRACK_AVAILABILITY_BANNED_BY_ARTIST \fP\fP
Track not available on artist's reqeust\&. 
.SS "enum \fBsp_bitrate\fP"
Bitrate definitions for music streaming 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_BITRATE_160k \fP\fP
Bitrate 160kbps\&. 
.TP
\fB\fISP_BITRATE_320k \fP\fP
Bitrate 320kbps\&. 
.TP
\fB\fISP_BITRATE_96k \fP\fP
Bitrate 96kbps\&. 
.SS "enum \fBsp_connection_rules\fP"
Connection rules, bitwise OR of flags
.PP
The default is SP_CONNECTION_RULE_NETWORK | SP_CONNECTION_RULE_ALLOW_SYNC 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_CONNECTION_RULE_NETWORK \fP\fP
Allow network traffic\&. When not set libspotify will force itself into offline mode\&. 
.TP
\fB\fISP_CONNECTION_RULE_NETWORK_IF_ROAMING \fP\fP
Allow network traffic even if roaming\&. 
.TP
\fB\fISP_CONNECTION_RULE_ALLOW_SYNC_OVER_MOBILE \fP\fP
Set to allow syncing of offline content over mobile connections\&. 
.TP
\fB\fISP_CONNECTION_RULE_ALLOW_SYNC_OVER_WIFI \fP\fP
Set to allow syncing of offline content over WiFi\&. 
.SS "enum \fBsp_connection_type\fP"
Current connection type set using \fBsp_session_set_connection_type()\fP 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_CONNECTION_TYPE_UNKNOWN \fP\fP
Connection type unknown (Default) 
.TP
\fB\fISP_CONNECTION_TYPE_NONE \fP\fP
No connection\&. 
.TP
\fB\fISP_CONNECTION_TYPE_MOBILE \fP\fP
Mobile data (EDGE, 3G, etc) 
.TP
\fB\fISP_CONNECTION_TYPE_MOBILE_ROAMING \fP\fP
Roamed mobile data (EDGE, 3G, etc) 
.TP
\fB\fISP_CONNECTION_TYPE_WIFI \fP\fP
Wireless connection\&. 
.TP
\fB\fISP_CONNECTION_TYPE_WIRED \fP\fP
Ethernet cable, etc\&. 
.SS "enum \fBsp_connectionstate\fP"
Describes the current state of the connection 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_CONNECTION_STATE_LOGGED_OUT \fP\fP
User not yet logged in\&. 
.TP
\fB\fISP_CONNECTION_STATE_LOGGED_IN \fP\fP
Logged in against a Spotify access point\&. 
.TP
\fB\fISP_CONNECTION_STATE_DISCONNECTED \fP\fP
Was logged in, but has now been disconnected\&. 
.TP
\fB\fISP_CONNECTION_STATE_UNDEFINED \fP\fP
The connection state is undefined\&. 
.TP
\fB\fISP_CONNECTION_STATE_OFFLINE \fP\fP
Logged in in offline mode\&. 
.SS "enum \fBsp_playlist_offline_status\fP"
Playlist offline status 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_PLAYLIST_OFFLINE_STATUS_NO \fP\fP
Playlist is not offline enabled\&. 
.TP
\fB\fISP_PLAYLIST_OFFLINE_STATUS_YES \fP\fP
Playlist is synchronized to local storage\&. 
.TP
\fB\fISP_PLAYLIST_OFFLINE_STATUS_DOWNLOADING \fP\fP
This playlist is currently downloading\&. Only one playlist can be in this state any given time\&. 
.TP
\fB\fISP_PLAYLIST_OFFLINE_STATUS_WAITING \fP\fP
Playlist is queued for download\&. 
.SS "enum \fBsp_playlist_type\fP"
Playlist types 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_PLAYLIST_TYPE_PLAYLIST \fP\fP
A normal playlist\&. 
.TP
\fB\fISP_PLAYLIST_TYPE_START_FOLDER \fP\fP
Marks a folder starting point,\&. 
.TP
\fB\fISP_PLAYLIST_TYPE_END_FOLDER \fP\fP
and ending point\&. 
.TP
\fB\fISP_PLAYLIST_TYPE_PLACEHOLDER \fP\fP
Unknown entry\&. 
.SS "enum \fBsp_sampletype\fP"
Sample type descriptor 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_SAMPLETYPE_INT16_NATIVE_ENDIAN \fP\fP
16-bit signed integer samples 
.SS "enum \fBsp_search_type\fP"
Search types 
.SS "enum \fBsp_track_offline_status\fP"
Track offline status 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_TRACK_OFFLINE_NO \fP\fP
Not marked for offline\&. 
.TP
\fB\fISP_TRACK_OFFLINE_WAITING \fP\fP
Waiting for download\&. 
.TP
\fB\fISP_TRACK_OFFLINE_DOWNLOADING \fP\fP
Currently downloading\&. 
.TP
\fB\fISP_TRACK_OFFLINE_DONE \fP\fP
Downloaded OK and can be played\&. 
.TP
\fB\fISP_TRACK_OFFLINE_ERROR \fP\fP
Error during download\&. 
.TP
\fB\fISP_TRACK_OFFLINE_DONE_EXPIRED \fP\fP
Downloaded OK but not playable due to expiery\&. 
.TP
\fB\fISP_TRACK_OFFLINE_LIMIT_EXCEEDED \fP\fP
Waiting because device have reached max number of allowed tracks\&. 
.TP
\fB\fISP_TRACK_OFFLINE_DONE_RESYNC \fP\fP
Downloaded OK and available but scheduled for re-download\&. 
.SH "Function Documentation"
.PP 
.SS "int \fBsp_offline_num_playlists\fP (\fBsp_session\fP *session)"
Return number of playlisys that is marked for offline synchronization
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object
.RE
.PP
\fBReturns:\fP
.RS 4
Number of playlists 
.RE
.PP

.SS "bool \fBsp_offline_sync_get_status\fP (\fBsp_session\fP *session, \fBsp_offline_sync_status\fP *status)"
Return offline synchronization status\&. When the internal status is updated the offline_status_updated() callback will be invoked\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object 
.br
\fIstatus\fP Status object that will be filled with info
.RE
.PP
\fBReturns:\fP
.RS 4
false if no synching is in progress (in which case the contents of status is undefined) 
.RE
.PP

.SS "int \fBsp_offline_time_left\fP (\fBsp_session\fP *session)"
Return remaining time (in seconds) until the offline key store expires and the user is required to relogin
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object 
.RE
.PP
\fBReturns:\fP
.RS 4
Seconds until expiration 
.RE
.PP

.SS "int \fBsp_offline_tracks_to_sync\fP (\fBsp_session\fP *session)"
Get total number of tracks that needs download before everything from all playlists that is marked for offline is fully synchronized
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object
.RE
.PP
\fBReturns:\fP
.RS 4
Number of tracks 
.RE
.PP

.SS "\fBsp_connectionstate\fP \fBsp_session_connectionstate\fP (\fBsp_session\fP *session)"
The connection state of the specified session\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object
.RE
.PP
\fBReturns:\fP
.RS 4
The connection state - see the sp_connectionstate enum for possible values 
.RE
.PP

.SS "\fBsp_error\fP \fBsp_session_create\fP (const \fBsp_session_config\fP *config, \fBsp_session\fP **sess)"
Initialize a session\&. The session returned will be initialized, but you will need to log in before you can perform any other operation Currently it is not supported to have multiple active sessions, and it's recommended to only call this once per process\&.
.PP
Here is a snippet from \fCspshell\&.c:\fP  
.PP
.nf
  config\&.api_version = SPOTIFY_API_VERSION;

    // The path of the directory to store the cache\&. This must be specified\&.
    // Please read the documentation on preferred values\&.
    config\&.cache_location = selftest ? '' : 'tmp';

    // The path of the directory to store the settings\&. 
    // This must be specified\&.
    // Please read the documentation on preferred values\&.
    config\&.settings_location = selftest ? '' : 'tmp';

    // The key of the application\&. They are generated by Spotify,
    // and are specific to each application using libspotify\&.
    config\&.application_key = g_appkey;
    config\&.application_key_size = g_appkey_size;

    // This identifies the application using some
    // free-text string [1, 255] characters\&.
    config\&.user_agent = 'spshell';

#if SP_WITH_CURL
    config\&.ca_certs_filename = '\&.\&./cacerts\&.pem';
#endif

    // Register the callbacks\&.
    config\&.callbacks = &callbacks;

    error = sp_session_create(&config, &session);
    if (SP_ERROR_OK != error) {
        fprintf(stderr, 'failed to create session: %s\n',
                        sp_error_message(error));
        return 2;
    }

.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIconfig\fP The configuration to use for the session 
.br
\fIsess\fP If successful, a new session - otherwise NULL
.RE
.PP
\fBReturns:\fP
.RS 4
One of the following errors, from \fBsp_error\fP SP_ERROR_OK SP_ERROR_BAD_API_VERSION SP_ERROR_BAD_USER_AGENT SP_ERROR_BAD_APPLICATION_KEY SP_ERROR_API_INITIALIZATION_FAILED SP_ERROR_INVALID_DEVICE_ID 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBjukebox\&.c\fP\&.
.SS "void \fBsp_session_flush_caches\fP (\fBsp_session\fP *session)"
Flush the caches
.PP
This will make libspotify write all data that is meant to be stored on disk to the disk immediately\&. libspotify does this periodically by itself and also on logout\&. So under normal conditions this should never need to be used\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.RE
.PP

.SS "void \fBsp_session_forget_me\fP (\fBsp_session\fP *session)"
Remove stored credentials in libspotify\&. If no credentials are currently stored, nothing will happen\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.RE
.PP

.SS "bool \fBsp_session_get_volume_normalization\fP (\fBsp_session\fP *session)"
Return status of volume normalization
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object
.RE
.PP
\fBReturns:\fP
.RS 4
true iff volume normalization is enabled 
.RE
.PP

.SS "\fBsp_playlist\fP* \fBsp_session_inbox_create\fP (\fBsp_session\fP *session)"
Returns an inbox playlist for the currently logged in user
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object
.RE
.PP
\fBReturns:\fP
.RS 4
A playlist or NULL if no user is logged in 
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the playlist when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_playlist_release()\fP 
.RE
.PP

.SS "void \fBsp_session_login\fP (\fBsp_session\fP *session, const char *username, const char *password, boolremember_me, const char *blob)"
Logs in the specified username/password combo\&. This initiates the login in the background\&. A callback is called when login is complete
.PP
An application MUST NEVER store the user's password in clear text\&. If automatic relogin is required, use \fBsp_session_relogin()\fP
.PP
Here is a snippet from \fCspshell\&.c:\fP  
.PP
.nf
     sp_session_login(session, username, password, 1, blob);
    }

.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.br
\fIusername\fP The username to log in 
.br
\fIpassword\fP The password for the specified username 
.br
\fIremember_me\fP If set, the username / password will be remembered by libspotify 
.br
\fIblob\fP If you have received a blob in the #credentials_blob_updated you can pas this here instead of password 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBjukebox\&.c\fP\&.
.SS "void \fBsp_session_logout\fP (\fBsp_session\fP *session)"
Logs out the currently logged in user
.PP
Always call this before terminating the application and libspotify is currently logged in\&. Otherwise, the settings and cache may be lost\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.RE
.PP

.SS "\fBsp_error\fP \fBsp_session_player_load\fP (\fBsp_session\fP *session, \fBsp_track\fP *track)"
Loads the specified track
.PP
After successfully loading the track, you have the option of running \fBsp_session_player_play()\fP directly, or using \fBsp_session_player_seek()\fP first\&. When this call returns, the track will have been loaded, unless an error occurred\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.br
\fItrack\fP The track to be loaded
.RE
.PP
\fBReturns:\fP
.RS 4
One of the following errors, from \fBsp_error\fP SP_ERROR_OK SP_ERROR_MISSING_CALLBACK SP_ERROR_RESOURCE_NOT_LOADED SP_ERROR_TRACK_NOT_PLAYABLE 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBjukebox\&.c\fP\&.
.SS "void \fBsp_session_player_play\fP (\fBsp_session\fP *session, boolplay)"
Play or pause the currently loaded track
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.br
\fIplay\fP If set to true, playback will occur\&. If set to false, the playback will be paused\&. 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBjukebox\&.c\fP\&.
.SS "\fBsp_error\fP \fBsp_session_player_prefetch\fP (\fBsp_session\fP *session, \fBsp_track\fP *track)"
Prefetch a track
.PP
Instruct libspotify to start loading of a track into its cache\&. This could be done by an application just before the current track ends\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.br
\fItrack\fP The track to be prefetched
.RE
.PP
\fBReturns:\fP
.RS 4
One of the following errors, from \fBsp_error\fP SP_ERROR_NO_CACHE SP_ERROR_OK
.RE
.PP
\fBNote:\fP
.RS 4
Prefetching is only possible if a cache is configured 
.RE
.PP

.SS "void \fBsp_session_player_seek\fP (\fBsp_session\fP *session, intoffset)"
Seek to position in the currently loaded track
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.br
\fIoffset\fP Track position, in milliseconds\&. 
.RE
.PP

.SS "void \fBsp_session_player_unload\fP (\fBsp_session\fP *session)"
Stops the currently playing track
.PP
This frees some resources held by libspotify to identify the currently playing track\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBjukebox\&.c\fP\&.
.SS "\fBsp_playlistcontainer\fP* \fBsp_session_playlistcontainer\fP (\fBsp_session\fP *session)"
Returns the playlist container for the currently logged in user\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object
.RE
.PP
\fBReturns:\fP
.RS 4
Playlist container object, NULL if not logged in 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBjukebox\&.c\fP\&.
.SS "void \fBsp_session_preferred_bitrate\fP (\fBsp_session\fP *session, \fBsp_bitrate\fPbitrate)"
Set preferred bitrate for music streaming
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object 
.br
\fIbitrate\fP Preferred bitrate, see \fBsp_bitrate\fP for possible values 
.RE
.PP

.SS "void \fBsp_session_preferred_offline_bitrate\fP (\fBsp_session\fP *session, \fBsp_bitrate\fPbitrate, boolallow_resync)"
Set preferred bitrate for offline sync
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object 
.br
\fIbitrate\fP Preferred bitrate, see \fBsp_bitrate\fP for possible values 
.br
\fIallow_resync\fP Set to true if libspotify should resynchronize already synchronized tracks\&. Usually you should set this to false\&. 
.RE
.PP

.SS "void \fBsp_session_process_events\fP (\fBsp_session\fP *session, int *next_timeout)"
Make the specified session process any pending events
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.br
\fInext_timeout\fP Stores the time (in milliseconds) until you should call this function again 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBjukebox\&.c\fP\&.
.SS "\fBsp_playlistcontainer\fP* \fBsp_session_publishedcontainer_for_user_create\fP (\fBsp_session\fP *session, const char *canonical_username)"
Return the published container for a given \fIcanonical_username\fP, or the currently logged in user if \fIcanonical_username\fP is NULL\&.
.PP
When done with the list you should call sp_playlistconatiner_release() to decrese the reference you own by having created it\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object\&. 
.br
\fIcanonical_username\fP The canonical username, or NULL\&.
.RE
.PP
\fBReturns:\fP
.RS 4
Playlist container object, NULL if not logged in\&. 
.RE
.PP

.SS "void \fBsp_session_release\fP (\fBsp_session\fP *sess)"
Release the session\&. This will clean up all data and connections associated with the session
.PP
\fBParameters:\fP
.RS 4
\fIsess\fP Session object returned from \fBsp_session_create()\fP 
.RE
.PP

.SS "\fBsp_error\fP \fBsp_session_relogin\fP (\fBsp_session\fP *session)"
Log in the remembered user if last user that logged in logged in with remember_me set\&. If no credentials are stored, this will return SP_ERROR_NO_CREDENTIALS\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object
.RE
.PP
\fBReturns:\fP
.RS 4
One of the following errors, from \fBsp_error\fP SP_ERROR_OK SP_ERROR_NO_CREDENTIALS 
.RE
.PP

.SS "int \fBsp_session_remembered_user\fP (\fBsp_session\fP *session, char *buffer, size_tbuffer_size)"
Get username of the user that will be logged in via \fBsp_session_relogin()\fP
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.br
\fIbuffer\fP The buffer to hold the username 
.br
\fIbuffer_size\fP The max size of the buffer that will hold the username\&. The resulting string is guaranteed to always be null terminated if buffer_size > 0
.RE
.PP
\fBReturns:\fP
.RS 4
The number of characters in the username\&. If value is greater or equal than \fCbuffer_size\fP, output was truncated\&. If returned value is -1 no credentials are stored in libspotify\&. 
.RE
.PP

.SS "void \fBsp_session_set_cache_size\fP (\fBsp_session\fP *session, size_tsize)"
Set maximum cache size\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object 
.br
\fIsize\fP Maximum cache size in megabytes\&. Setting it to 0 (the default) will let libspotify automatically resize the cache (10% of disk free space) 
.RE
.PP

.SS "void \fBsp_session_set_connection_rules\fP (\fBsp_session\fP *session, \fBsp_connection_rules\fPrules)"
Set rules for how libspotify connects to Spotify servers and synchronizes offline content
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object 
.br
\fIrules\fP Connection rules
.RE
.PP
\fBNote:\fP
.RS 4
Used in conjunction with \fBsp_session_set_connection_type()\fP to control how libspotify should behave in respect to network activity and offline synchronization\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_connection_rules\fP 
.RE
.PP

.SS "void \fBsp_session_set_connection_type\fP (\fBsp_session\fP *session, \fBsp_connection_type\fPtype)"
Set to true if the connection is currently routed over a roamed connectivity
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object 
.br
\fItype\fP Connection type
.RE
.PP
\fBNote:\fP
.RS 4
Used in conjunction with \fBsp_session_set_connection_rules()\fP to control how libspotify should behave in respect to network activity and offline synchronization\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_connection_type\fP 
.RE
.PP

.SS "void \fBsp_session_set_volume_normalization\fP (\fBsp_session\fP *session, boolon)"
Set volume normalization
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object 
.br
\fIon\fP True iff volume normalization should be enabled 
.RE
.PP

.SS "\fBsp_playlist\fP* \fBsp_session_starred_create\fP (\fBsp_session\fP *session)"
Returns the starred list for the current user
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object
.RE
.PP
\fBReturns:\fP
.RS 4
A playlist or NULL if no user is logged in 
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the playlist when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_playlist_release()\fP 
.RE
.PP

.SS "\fBsp_playlist\fP* \fBsp_session_starred_for_user_create\fP (\fBsp_session\fP *session, const char *canonical_username)"
Returns the starred list for a user
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object 
.br
\fIcanonical_username\fP Canonical username
.RE
.PP
\fBReturns:\fP
.RS 4
A playlist or NULL if no user is logged in 
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the playlist when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_playlist_release()\fP 
.RE
.PP

.SS "\fBsp_user\fP* \fBsp_session_user\fP (\fBsp_session\fP *session)"
Fetches the currently logged in user
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object
.RE
.PP
\fBReturns:\fP
.RS 4
The logged in user (or NULL if not logged in) 
.RE
.PP

.SS "int \fBsp_session_user_country\fP (\fBsp_session\fP *session)"
Get currently logged in users country updated the offline_status_updated() callback will be invoked\&.
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session object
.RE
.PP
\fBReturns:\fP
.RS 4
Country encoded in an integer 'SE' = 'S' << 8 | 'E' 
.RE
.PP

.SS "void* \fBsp_session_userdata\fP (\fBsp_session\fP *session)"
The userdata associated with the session
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Your session object
.RE
.PP
\fBReturns:\fP
.RS 4
The userdata that was passed in on session creation 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libspotify from the source code\&.
